home *** CD-ROM | disk | FTP | other *** search
/ Popular Request / By Popular Request (Arsenal Computer)(SysOptics Distribution System).ISO / amiga1 / clphst10.lha / ClipHistory / ClipHistory.man < prev    next >
Text File  |  1994-04-03  |  19KB  |  469 lines
  1.  
  2.  
  3.    This file describes ClipHistory, version 1.0, a program that adds
  4. a history to the clipboard.
  5.  
  6. Introduction
  7. ************
  8.  
  9.    This is a program that I've been thinking of doing for a long time,
  10. but I haven't actually implemented it until now. I think first I got
  11. the idea when I had used the history feature of PowerSnap (by Nico
  12. Franτois) a little while. I soon realised that it was a very
  13. convenient feature.
  14.  
  15.    But other programs uses the clipboard as well. The history
  16. PowerSnap maintains only applies to the text that PowerSnap
  17. writes to the clipboard, not the ones e.g. my editor writes. And I
  18. thought that it would indeed be useful to have them in a history too.
  19.  
  20.    One problem with such a history is that it easily can eat up a lot
  21. of memory, since cuts and copies in an editor can be rather large at
  22. times. To remedy this problem, there are several filtering options,
  23. that limits the amount of memory ClipHistory may use. But more about
  24. this later on in this document.
  25.  
  26.    One interesting detail: ClipHistory is a completely system friendly
  27. program, in that it doesn't patch any functions at all. It only uses
  28. well documented features of the operating system. This does have a
  29. minor drawback: ClipHistory can miss clips, if several clips are
  30. written in a very short time. But this shouldn't be any problem, I
  31. think.. :)
  32.  
  33. Legal information
  34. *****************
  35.  
  36.        ClipHistory is freeware, i.e. copyrighted, freely distributable
  37. software. Feel free to use and copy this program, as long as the
  38. following restrictions are fulfilled:
  39.  
  40.    *  All files are copied without any alterations. If any extra files
  41.      are added, it must be obvious that they don't belong to the
  42.      original distribution, nor that they don't must be included in any
  43.      redistribution.
  44.  
  45.      Exception: So called "BBS ads" may not be added.
  46.  
  47.    *  The copying is done on a non-commercial basis. A small fee to
  48.      cover media costs etc. may be charged.
  49.  
  50.    *  The copier isn't claiming the copyright of this program.
  51.  
  52.    Any exeptions from the above requires a written permission from the
  53. author.
  54.  
  55. No warranty
  56. ===========
  57.  
  58.    THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY
  59. APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  60. HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT
  61. WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  62. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  63. PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
  64. OF THE PROGRAMS IS WITH YOU.  SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU
  65. ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  66.  
  67.    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  68. WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
  69. REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  70. DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
  71. DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS
  72. (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  73. INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
  74. THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER
  75. OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  76.  
  77. System requirements
  78. *******************
  79.  
  80.        ClipHistory have very modest system requirements. It needs OS
  81. 2.04 or better, although OS 3.0 or better will make ClipHistory
  82. operate slightly better.. :)
  83.  
  84.    If you have ReqTools (by Nico Franτois) installed, then
  85. ClipHistory will use ReqTools for its requesters (you can
  86. disable this if you like). Otherwise the "normal" system requesters
  87. will be used.
  88.  
  89. Installation
  90. ************
  91.  
  92.        ClipHistory is easy to install. Simply copy the program (and
  93. its icon) to WBStartup, or whereever you find convenient. If you have
  94. OS 2.1 or better, you might want to copy a catalog file as well, to make
  95. ClipHistory operate in another language than english.
  96.  
  97.    The easiest way is to let the Installer do it (if you have it that
  98. is!  :). If not, copy the file cliphistory.catalog as found in the
  99. Catalogs/<language> drawer to Locale:Catalogs/<language> (or to a
  100. the drawer Catalogs/<language> in the same drawer as you placed
  101. ClipHistory. In either case, <language> should be one of the
  102. languages you have select in the Locale preferences editor.
  103.  
  104.    If there is no catalog file for your language, please try to fill in
  105. the file Empty.ct in the Catalogs drawer and send it to me. I will
  106. then include the catalog in the next release of ClipHistory.
  107.  
  108. Usage
  109. *****
  110.  
  111.    To use ClipHistory, you first make sure that the tooltypes are set
  112. up properly. Then start it. You can also start if from a shell, but
  113. then you must remember to Run it (and to write suitble arguments). To
  114. make it permanently installed, simply drop it into WBStartup, or
  115. enter a suitable line in your S:User-Startup file.
  116.  
  117.        ClipHistory installs itself as a commodity, so you can use the
  118. Commodities Exchange program to show the interface, disable/enable it,
  119. or remove it completely. Starting ClipHistory a second time (for the
  120. same clipboard unit) will cause the first copy to show the interface.
  121. Pressing the hotkey will also open the interface (CX_POPKEY, see
  122. Options).
  123.  
  124.    The user interface of ClipHistory is very simple; it contains of a
  125. window with a list gadget. This list contains all the remembered clips.
  126. There is also a menu attached (see Menus).
  127.  
  128.    The text showed in the list is either the text - if it is a text
  129. clip - or the type of the IFF clip (everything on the clipboard should
  130. be in IFF format), followed by its size (in bytes). If you have OS 3.0
  131. or higher, the non-text clips will be shown in bold (or at least
  132. something similar to bold).
  133.  
  134.    To select an item in the list, you either click once on it with the
  135. mouse, or you use the cursur up/down keys (optionally with the
  136. shift/alt/ctrl qualifiers) to highlight the requested item.
  137.  
  138.    To copy an item to the clipboard, you double-click on the item, or
  139. press return when the proper item is selected. Unless the STICKY
  140. option (see Options) have been used, the window will close.
  141.  
  142.    Escape closes the window.
  143.  
  144. Menus
  145. *****
  146.  
  147.    The window ClipHistory opens have the following menus:
  148.  
  149. Project
  150.     Save clip as...
  151.           This allows you to save the currently selected item to a file
  152.           of your choice.
  153.  
  154.     About...
  155.           Shows some information about the program and the history.
  156.  
  157.     Hide
  158.           Close the window, but don't quit.
  159.  
  160.     Quit
  161.           Close the window and quit.
  162.  
  163. Edit
  164.     Delete...
  165.           This will delete the currently selected item. You can also
  166.           press Del to do this.
  167.  
  168.     Delete all...
  169.           This will delete all clips in the list. You can also press
  170.           Shift-Del to do this.
  171.  
  172. Options
  173.     Create icons?
  174.           If checked, then icons will be created for the files you
  175.           save. This is the same as the option CREATEICONS (see
  176.           Options).
  177.  
  178.     Save text as IFF?
  179.           If checked, then text clips (those that shows up as "normal"
  180.           text in the window) will be saved as IFF files. If you save
  181.           them as normal text, then some information might be lost
  182.           (technical note: all CHRS chunks will be saved, but no
  183.           other). Same as the option TEXTASIFF (see Options).
  184.  
  185.     ReqTools?
  186.           If checked, then ReqTools will be used for requesters, if
  187.           ReqTools is available, that is. Same as the option
  188.           REQTOOLS (see Options).
  189.  
  190. Options
  191. *******
  192.  
  193.    Options can be specified in the tooltypes (when starting from the
  194. Workbench) or on the command line (when starting from a Shell).
  195.  
  196. CX_PRIORITY
  197.      This value specifies the priority ClipHistory will have in the
  198.      commodities input chain. This priority only applies to the hotkey.
  199.      Default is 0. Accpted range is -128 to 127.
  200.  
  201. CX_POPKEY
  202.      This specifies the hotkey to use to open the window. Default is
  203.      "control lalt c". Please refer to your Amiga manual for more
  204.      information about hotkey descriptors.
  205.  
  206.          Note: If this string is 100 chars long or more,
  207.      unpredictable things may happen when you open the window. There is
  208.      (currently) no check for this.  I hope this doesn't cause any
  209.      problems for anyone... :)
  210.  
  211. CX_POPUP
  212.      If YES, then ClipHistory will open the window upon startup (this
  213.      is the default). Use NO to disable this.
  214.  
  215. CLIPUNIT
  216.      This value specifies the clipboard unit to use. Default is 0.
  217.      Accepted range is 0 to 255.
  218.  
  219.      You can start one copy of ClipHistory for each clipboard unit. In
  220.      Commodities Exchange, the name will be "ClipHistory <unit>",
  221.      where <unit> is the unit you specify here.
  222.  
  223. TOOLPRI
  224.      This argument specifies the "normal" priority for ClipHistory.
  225.      To make sure that ClipHistory doesn't miss any clips, even if
  226.      the computer is doing much work, you might want to rise the task
  227.      priority of ClipHistory. Default is to use whatever priority
  228.      ClipHistory was started in (this is normally 0). Accepted range
  229.      is -128 to 4.
  230.  
  231.      Note: The Workbench also supports the TOOLPRI tooltype. It was
  232.      added to ClipHistory so that Shell users easily can change the
  233.      priority as well.
  234.  
  235. WORKPRI
  236.      Some operations ClipHistory does can take a little time
  237.      sometimes.  Here you can specify the priority ClipHistory should
  238.      use during this time, so that other programs can run normally.
  239.      Usually a negative value should be entered. Default is not to
  240.      change the priority. Accepted range is -128 to 4.
  241.  
  242. SILENT
  243.      If YES, then don't display any requesters for "clip operation
  244.      errors", like when there was a problem reading/writing to the
  245.      clipboard, or when there wasn't enough memory to save a clip.
  246.      Default is NO.
  247.  
  248. PUBSCREEN
  249.      This specifies the public screen on which ClipHistory should
  250.      open its window on. Default is the frontmost screen if it is
  251.      public (if OPENONALL is on, it will use the frontmost screen
  252.      anyway), or the default public screen.
  253.  
  254. OPENONALL
  255.      If YES, then ClipHistory will open on the frontmost screen,
  256.      regardless if it is public or not. Default is NO.
  257.  
  258.          Note: In order for this to work properly, a function in
  259.      Intuition (CloseScreen()) needs to be patched (this patch
  260.      is only installed if this option have been activated). This might
  261.      make it impossible for ClipHistory to remove itself from the
  262.      system if some other program have patched the same function. If
  263.      you have a SetMan-like program installed, this should never
  264.      happen.
  265.  
  266. FONTNAME
  267.      This string specifies the name of the font (including the ".font"
  268.      extension) to use for the window/menus. If not specified, then the
  269.      current screen font is used. You must specify both FONTNAME and
  270.      FONTSIZE.
  271.  
  272.      Hint: If you have MagicWB, it can be a good idea to use e.g.
  273.      XHelvetica, since that font is "complete", i.e. chars than
  274.      normally aren't printable holds graphics to identify the char in
  275.      question.
  276.  
  277. FONTSIZE
  278.      This value specifies the size of the above font. You must specify
  279.      both FONTNAME and FONTSIZE.
  280.  
  281. WINDOWLEFT
  282.      Initial left edge of the window. Default is to center the window
  283.      on the screen.
  284.  
  285. WINDOWTOP
  286.      Initial top edge of the window. Default is to center the window on
  287.      the screen.
  288.  
  289. WINWIDTH
  290.      Initial width of the window. Default is <width of the screen>/2.
  291.  
  292. WINHEIGHT
  293.      Initial height of the window. Default is <width of the screen>/3.
  294.  
  295. STICKY
  296.      If YES, ClipHistory won't close the window after writing a clip
  297.      to the clipboard. Default is NO.
  298.  
  299. POPSCREEN
  300.      If YES, then ClipHistory will - when closing its window -
  301.      restore the screen that was in front before the window was opened.
  302.      This only needs to be done if that screen wasn't public. Default
  303.      is NO.
  304.  
  305.          Note: Using either PUBSCREEN, OPENONALL or STICKY will
  306.      disable this option.
  307.  
  308. SAVEPOS
  309.      If YES, then ClipHistory will remember the current position of
  310.      the window when you close it. Otherwise it will reopen using the
  311.      position specified in the arguments (or the defaults). Default is
  312.      NO.
  313.  
  314. SAVESIZE
  315.      If YES, then ClipHistory will remember the current size of the
  316.      window when you close it. Otherwise it will reopen using the size
  317.      specified in the arguments (or the defaults). Default is NO.
  318.  
  319. MAXCLIPS
  320.      Maximum number of clips that the history can hold. Any value
  321.      accpted. Note that 0 really means 1... Default is 32767 (the
  322.      listview handling routines in the OS can't cope with more, so.. :).
  323.  
  324. MAXCLIPSIZE
  325.      If the clip is larger than this value, then it will not be saved
  326.      in the history. Using 0 here will disable the history. Default is
  327.      the MAXMEM limit (see below) if that one is specified. Otherwise
  328.      there is no limit.
  329.  
  330. MINCLIPSIZE
  331.      If the clip is smaller than this, then it will not be saved in the
  332.      history.  Default is 0.
  333.  
  334.      Please note that this refers to the total size of the clip,
  335.      including the extra overhead due to the IFF file format. For a
  336.      minimal IFF file (as saved by e.g. PowerSnap), this overhead is
  337.      20 bytes. Also, an IFF file is (read: should be) always padded to
  338.      an even number of bytes.  Thus, a relatively useful minimum could
  339.      be 22, which would force each saved clip to have at least 3 data
  340.      bytes (when talking about saved text at least).
  341.  
  342. MAXMEM
  343.      This specifies how much memory the history may use at most. The
  344.      history is dynamically allocated, using so called memory pools (to
  345.      reduce memory fragmentation). Thus, the actual amount of memory
  346.      used might be a little more than this value. Default is no max
  347.      (other than the amount of free memory :).
  348.  
  349. MATCH
  350.      If YES, check all new items against the last one, and only save
  351.      the new one if it is different. Default is NO.
  352.  
  353. FULLMATCH
  354.      Like MATCH, but check all entries instead. Default is NO.
  355.  
  356.          Warning: This can take some time if you have a large history
  357.      (ClipHistory will use the WORKPRI (see above) during this
  358.      check). If more than one clip is written to the clipboard during
  359.      this time, only the last one will be remembered.
  360.  
  361. CASE
  362.      If NO, then ClipHistory will ignore the case when comparing two
  363.      clips (when either MATCH or FULLMATCH have been used).
  364.      Obviously, this is only possible when the clip contains text
  365.      (FTXT).  Default is YES.
  366.  
  367. FILTER
  368.      Here you can specify which IFF types that should be saved (or not
  369.      saved, if REJECT have been specified). Space separate the items.
  370.      Case is important. There are many different IFF types available,
  371.      and I can't mention them all, but here is a list over the most
  372.      common ones:
  373.  
  374.     FTXT
  375.           Text. ConClip and PowerSnap saves these ones.
  376.  
  377.     ILBM
  378.           Graphics/palettes. Saved by e.g. IconEdit.
  379.  
  380.     8SVX
  381.           Sound (samples).
  382.  
  383. REJECT
  384.      Make the FILTER (see above) reject on a match instead of accept,
  385.      i.e.  reverse the action of the filter.
  386.  
  387. TEXTASIFF
  388.      If YES, then FTXT clips will be saved as normal text instead of as
  389.      an IFF file. All clips that shows up as "normal" text in the
  390.      window are FTXT clips. Note that some information may be lost
  391.      (e.g. font information). Default is NO.
  392.  
  393. CREATEICONS
  394.      If YES, then an icon will be created for each clip saved. Default
  395.      is NO.
  396.  
  397. REQTOOLS
  398.      If YES, then ClipHistory will use ReqTools for requesters, if
  399.      it should be available. Default is YES.
  400.  
  401. Future
  402. ******
  403.  
  404.    There are a few things I might add to ClipHistory:
  405.  
  406.    *  More IFF parsing. Now it is minimal, only reading/writing exactly
  407.      what is on the clipboard, with a minor "support" for FTXT.
  408.      Enhanced parsing could e.g. reduce the overhead for FTXT clips, by
  409.      only saving the actual text.
  410.  
  411.    *  Separate accept and reject filters. I would need to alter the way
  412.      they are specified though (now I'm using ReadArgs() "/M"
  413.      specifier for this, and ReadArgs() don't like several "/M"
  414.      specifiers in one template.. :).
  415.  
  416.    *  Load of single clips and/or load/save of the entire history.
  417.  
  418.    *  Prefs window, to edit/save the settings. Perhaps as a separate
  419.      prefs program.
  420.  
  421.    *  A way to view a large clip in full. I'm not sure how, but
  422.      something could be nice. Perhaps writing the clip to a temporary
  423.      file, and let some viewer program handle it (like MultiView)?
  424.  
  425.    *  Some other way of "highlighting" non-text clips on OS 3.0 or
  426.      better.  Problem is that I don't know how I should change it.
  427.      Please tell me if you have any ideas.
  428.  
  429.    *  Make a Triton version (maybe ClipHistory will require
  430.      Triton).
  431.  
  432.    None of these things are important for me, but feel free to send me
  433. a note telling me what *you* would like to see added (see Author
  434. contact).
  435.  
  436. Author contact
  437. **************
  438.  
  439.    Feel free to send comments, bug reports, money, or whatever, to:
  440.  
  441.      S-mail:  Magnus Holmgren
  442.               RydsvΣgen 254 A:14
  443.               S-582 51  Link÷ping
  444.               SWEDEN
  445.      
  446.      E-mail:  cmh@augs.se (internet) or 2:204/404.6 (fidonet).
  447.  
  448. Acknowledgements
  449. ****************
  450.  
  451.    Thanks go to the following persons:
  452.  
  453. Nico Franτois
  454.      His program PowerSnap inspired me do write this program in the
  455.      first place. He also sent me a few small (but useful) functions I
  456.      needed, and came with a few suggestions/bug reports.
  457.  
  458. Nikolai Waldman
  459.      Suggestions.
  460.  
  461. Michael Berg
  462.      Bug report and suggestions.
  463.  
  464. Program history
  465. ***************
  466.  
  467.    Version 1.0: Initial release.
  468.  
  469.